GET Statement (File I-O)
 ----------------------------------------------------------------------------


 Action

 Reads from a disk file into a random-access buffer or variable.


 Syntax

  GET -#- filenumber%-,- recordnumber%- -,  variable--


 Remarks

 Do not use  GET on ISAM files.

 The  GET statement uses the following arguments.
-----------------------------------------------------------------------------
 Argument                                Description
 ----------------------------------------------------------------------------
  filenumber%                            The number used in the  OPEN
                                         statement to open the file.

  recordnumber%                          For random-access files, the
                                         number of the record to be read.
                                         For binary-mode files, the byte
                                         position where reading starts. The
                                         first record or byte position in a
                                         file is 1. If you omit
 Argument                                Description
 ----------------------------------------------------------------------------
                                         file is 1. If you omit
                                         recordnumber%, the next record or
                                         byte (the one after the last  GET
                                         or  PUT statement, or the one
                                         pointed to by the last  SEEK) is
                                         read into the buffer. The largest
                                         possible record number is 2to31 -1,
                                         or 2,147,483,647.

  variable                               The variable used to receive input
                                         from the file. If you specify a
                                         variable, you do not need to use
                                         CVI,  CVL,  CVS,  CVD, or  CVC to
                                         convert record fields to numbers.
                                         You cannot use a  FIELD statement
                                         with the file if you use the
                                         variable argument.

                                         For random-access files, you can
 Argument                                Description
 ----------------------------------------------------------------------------
                                         For random-access files, you can
                                         use any variable as long as the
                                         length of the variable is less
                                         than or equal to the length of the
                                         record. Usually, a record variable
                                         defined to match the fields in a
                                         data record is used.

                                         For binary-mode files, you can use
                                         any variable. The  GET statement
                                         reads as many bytes as there are
                                         in the variable.

                                         When you use a variable-length
                                         string variable, the statement
                                         reads as many bytes as there are
                                         characters in the string's value.
                                         For example, the following two
                                         statements read 10 bytes from file
 Argument                                Description
 ----------------------------------------------------------------------------
                                         statements read 10 bytes from file
                                         number 1.

                                         VarStrings$=STRING$ (10, " ")
                                         GET #1,,VarString$

                                         See the examples for more
                                         information about using variables
                                         rather than  FIELD statements for
                                         random-access files.



 A record cannot be longer than 32,767 bytes.

 You can omit  recordnumber%,  variable, or both. If you omit  recordnumber%
 but include a variable, you must still include the commas.

 GET #4,,FileBuffer

 If you omit both arguments, do not include the commas.

 GET #4

  GET and  PUT statements allow fixed-length input and output for BASIC
 communication files. Use  GET carefully, because if there is a communication
 failure,  GET waits indefinitely.


 Note

 When you use  GET with the  FIELD statement, you can use  INPUT # or  LINE
 INPUT # after a  GET statement to read characters from the random-access
 file buffer. You can use the  EOF function after a  GET statement to see if
 the  GET operation went beyond the end of the file.


 See Also

  CVI,  CVL,  CVS,  CVD,  CVC;  LSET;  MKI$,  MKL$,  MKS$,  MKD$,  MKC$; OPEN
 (File I-O);  PUT (File I-O)


 Example

 The following example creates a random-access test file that contains five
 names and corresponding test scores. It then displays the contents of the
 file using the  GET statement.

 ' Define record fields.
 TYPE TestRecord
     NameField  AS STRING * 20
     ScoreField AS SINGLE
 END TYPE
 ' Define a variable of the user type.
 DIM Rec AS TestRecord
 DIM I AS LONG

 ' This part of the program creates a random-access file to be used by
 ' the second part of the program, which demonstrates the GET statement.
 OPEN "TESTDAT2.DAT" FOR RANDOM AS #1 LEN = LEN(Rec)
 CLS
 RESTORE
 READ NameField$, ScoreField
 I = 0
 DO WHILE NameField$ <> "END"
     I = I + 1
     Rec.NameField = NameField$
     Rec.ScoreField = ScoreField
     PUT #1, I, Rec
     READ NameField$, ScoreField
 LOOP
 CLOSE #1
 DATA "John Simmons", 100
 DATA "Allie Simpson", 95
 DATA "Tom Tucker", 72
 DATA "Walt Wagner", 90
 DATA "Mel Zucker", 92
 DATA "END", 0

 ' Open the test data file.
 DIM FileBuffer AS TestRecord
 DIM Max AS LONG
 OPEN "TESTDAT2.DAT" FOR RANDOM AS #1 LEN = LEN(FileBuffer)
 'Calculate number of records in the file.
 Max = LOF(1) \ LEN(FileBuffer)

 ' Read and print contents of each record.
 FOR I = 1 TO Max
     GET #1, I, FileBuffer
     PRINT FileBuffer.NameField, FileBuffer.ScoreField
 NEXT I
 CLOSE #1
 ' Remove file from disk.
 KILL "TESTDAT2.DAT"
 END